/**
 * @(#)IdManager.java Jan 30, 2007
 *
 * Copyright (c) 2005-2010 Psiqueware S.A. de C.V. All Rights Reserved.
 * This software is the proprietary information Psiqueware S.A. de C.V.
 * Use is subject to license terms.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
 * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * <br/>Usuario : AngelElectrico
 * <br/>Creaci&oacute;n: Jan 30, 2007 - 4:08:02 PM
 * <br/>
 * <br/>
 * <br/><t5>Cambios :</t5>
 * <br/><b>Fecha | Autor  |  Cambios</b>
 * <ul>
 * <li>Jan 30, 2007 | <a href = "mailto:AngelElectrico@PsiqueWare.com">Angel El&eacute;ctrico</a> | Creaci&oacute;n del Objeto.</li>
 *
 * </ul>
 */

package com.psiqueware.alheli.id;

import com.psiqueware.alheli.dao.EnlaceTransaccional;
import com.psiqueware.alheli.manager.BaseManagerInterface;
import com.psiqueware.alheli.manager.ManagerException;

import java.util.Date;

/**
 * Encargado de la informacion de autenticacion de un {@link Usuario}.
 * <br/>Paquete Original: com.psiqueware.basico.id
 * <br/>Nombre  Original: AutentificadorTManager
 * <br/>Oprima para ver : <a href="IdManager.java.html"><i>C&oacute;digo Fuente</i> </a>
 *
 * @author <a href="mailto:AngelElectrico@PsiqueWare.com">Angel El&eacute;ctrico</a>
 * @version Revision: 1.1 Jan 30, 2007 4:08:02 PM
 */
public interface IdManager extends BaseManagerInterface, Sesionable
{

    /**
     * Genera una cadena semi-aleatoria util para realizar formas seguras.
     *
     * @return String semi-aleatoria de 16 caracteres de longitud.
     */
    String generaCadenaAleatoria16Caracteres();

    /**
     * Persistimos un nuevo {@link Identificacion}. Este nuevo Identificacion no se encuentra activado
     * es necesario activarlo para poder hacer uso de el.    Una excepci&oacute;n brotar&aacute; si el
     * {@link Usuario} ya ten&iacute;a un {@link Identificacion}; en ese caso utilizar  nuevaIdentificacion proporcionando
     * la contrase&ntilde;a anterior.   Para el {@link Dominio} por defecto (<code>null</code>).
     *
     * @param usuario             {@link Usuario} al que pertenece el {@link Identificacion}.
     * @param autenticacion       para autenticar a este {@link Usuario}.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return nuevo {@link Identificacion} persitido.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          en caso de no poder completar la operaci&oacute;n.
     */
    Identificacion nuevaIdentificacion(final Usuario usuario, final char[] autenticacion, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Cambia la informacion de autenticacion del {@link Identificacion}.
     * <p/>
     * Para el {@link Dominio} Asignado al {@link Usuario}.
     * <p/>
     * Esta operaci&oacute;n tambien puede ser utilizada en los casos en los que el {@link Identificacion} no haya
     * sido activado previamente y se desee hacerlo. En este caso la autentificacion anterior
     * puede ser igual a la nueva, el valor de activaci&oacute;n permanecer&aacute; desactivado.
     *
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     * @param usuario             cuyo {@link Identificacion} vamos a reemplazar.
     * @param authAnterior        para validar cambio.
     * @param authNueva           nuevo password.
     *
     * @return {@link Identificacion} con los cambios en caso de ser
     *         valida la informacion; <code>null</code> en caso contrario.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          en caso de no poder completar la operaci&oacute;n.
     * @noinspection CastToConcreteClass
     */
    Identificacion nuevaIdentificacion(final Usuario usuario, final char[] authAnterior, final char[] authNueva, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Activa un login a partir de este. Marca como probado un correoElectronico y el login como activado.
     *
     * @param identificacion      A activar.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return <code>true</code> si se logro activar el login; <code>false</code> en caso contrario.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          en caso de no poder activar el login.
     * @noinspection CallToStringEquals
     */
    Boolean activarIdentificacion(final Identificacion identificacion, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Activa un login a partir de registrar su correoElectronico en el sistema. Marca como probado un correoElectronico y el login como activado.
     *
     * @param identificacion      nombre del usuario a activar.
     * @param claveActivacion     clave de activacion del correoElectronico del usuario.
     * @param autenticacion       para el usuario.
     * @param idDominio           id del {@link Dominio} al que pertenece la identificacion; <code>null</code> si no hay ninguno.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return <code>true</code> si se logro activar el login; <code>false</code> en caso contrario.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          en caso de no poder activar el login.
     * @noinspection CallToStringEquals
     */
    Boolean activarIdentificacion(final String identificacion, final char[] autenticacion, final String claveActivacion, final Long idDominio, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Activa un login a partir de registrar su correoElectronico en el sistema.
     * Esto solo funciona para activar el primer login de un usuario.
     * Marca como probado un correoElectronico y el login como activado.
     *
     * @param identificacion      nombre del usuario a activar.
     * @param claveActivacion     clave de activacion del correoElectronico del usuario.
     * @param idDominio           id del {@link Dominio} al que pertenece la identificacion; <code>null</code> si no hay ninguno.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return <code>true</code> si se logro activar el login; <code>false</code> en caso contrario.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          en caso de no poder activar el login.
     * @noinspection CallToStringEquals
     */
    Boolean activarIdentificacion(final String identificacion, final String claveActivacion, final Long idDominio, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Determina si un Usuario puede entrar al sistema.   Para el {@link Dominio} por defecto (<code>null</code>).
     *
     * @param identificacion      del {@link Identificacion} que se busca
     * @param autenticacion       del {@link Identificacion} que se busca
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return {@link Identificacion} en caso de encontrarlo, <code>null</code> en caso de no poder entrar al sistema.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          si se presenta alg&uacute;n problema al acceder a persistencia.
     */
    Identificacion identificar(final String identificacion, final char[] autenticacion, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Identifica autom&aacute;ticamente al {@link Usuario} cuya identificaci&oacute;n es proporcionada.
     * Busca la informaci&oacute;n del {@link Identificacion} en persistencia y luego realiza un logeo
     * en el {@link Sesionable} de esta informaci&oacute;n.
     * <p/>
     * Para el {@link Dominio} por defecto (<code>null</code>).
     * <p/>
     * <b>&Uacute;sese con cautela. Esta operaci&oacute;n puede facilitar la entrada al sistema a un usuario sin las credenciales correctas.</b>
     *
     * @param identificacion      del {@link Usuario}.
     * @param sesionable          donde se realizar&aacute; el login.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return <code>true</code> si se pudo identificar el usuario; <code>false</code> en caso contrario.
     *
     * @throws ManagerException si no se puede realizar la acci&oacute;n.
     */
    boolean identificar(final String identificacion, final Sesionable sesionable, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Determina si un Usuario puede entrar al sistema.   Para el {@link Dominio} por defecto (<code>null</code>).
     *
     * @param identificacion      del {@link Identificacion} que se busca
     * @param autenticacion       del {@link Identificacion} que se busca
     * @param dominio             donde aplica el {@link Usuario}.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return {@link Identificacion} en caso de encontrarlo, <code>null</code> en caso de no poder entrar al sistema.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException
     *          si se presenta alg&uacute;n problema al acceder a persistencia.
     */
    Identificacion identificar(final String identificacion, final char[] autenticacion, final Dominio dominio, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Identifica autom&aacute;ticamente al {@link Usuario} cuya identificaci&oacute;n es proporcionada.
     * Busca la informaci&oacute;n del {@link Identificacion} en persistencia y luego realiza un logeo
     * en el {@link Sesionable} de esta informaci&oacute;n.
     * <p/>
     * Para el {@link Dominio} por defecto (<code>null</code>).
     * <p/>
     * <b>&Uacute;sese con cautela. Esta operaci&oacute;n puede facilitar la entrada al sistema a un usuario sin las credenciales correctas.</b>
     *
     * @param identificacion      del {@link Usuario}.
     * @param sesionable          donde se realizar&aacute; el login.
     * @param dominio             donde aplica el {@link Usuario}.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return <code>true</code> si se pudo identificar el usuario; <code>false</code> en caso contrario.
     *
     * @throws ManagerException si no se puede realizar la acci&oacute;n.
     */
    boolean identificar(final String identificacion, final Sesionable sesionable, final Dominio dominio, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;


    /**
     * Identifica al {@link Usuario} cuya {@link Identificacion} es proporcionada.
     * <p/>
     * <p/>
     * Para el {@link Dominio} por defecto (<code>null</code>).
     * <p/>
     *
     * @param identificacion      con los datos de identificaci&oacute;n.
     * @param sesionable          donde se realizar&aacute; el identificacion.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return <code>true</code> si se pudo identificar el usuario; <code>false</code> en caso contrario.
     *
     * @throws ManagerException si no se puede realizar la acci&oacute;n.
     */
    boolean identificar(final Identificacion identificacion, final Sesionable sesionable, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Genera una cadena que permite el regenerar el {@link Identificacion} de un {@link Usuario}.
     *
     * @param usuario             cuyo {@link Identificacion} se pretende regenerar.
     * @param fechaExpiracion     fecha en la que se caducar&aacute; la cadena de regeneraci&oacute;n. Puede ser <code>null</code> si no se requiere que caduque la cadena.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return La cadena de regeneraci&oacute;n.
     *
     * @throws ManagerException si no se puede realizar la acci&oacute;n.
     */
    String generarCadenaRegeneracionIdentificacion(final Usuario usuario, final Date fechaExpiracion, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Genera una cadena que permite activar la {@link Identificacion} de un {@link Usuario}. El {@link Usuario} tiene
     * que tener una {@link Identificacion} sin activar.
     *
     * @param usuario             cuyo {@link Identificacion} se pretende activar.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return La cadena de activaci&oacute;n; <code>null</code> si no se pudo generar una nueva cadena.
     *
     * @throws com.psiqueware.alheli.manager.ManagerException si no se puede realizar la acci&oacute;n.
     */
    String regenerarClaveActivacionIdentificacion(final Usuario usuario, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

    /**
     * Regenera el {@link Identificacion} de un {@link Usuario} a partir de la cadena de regeneraci&oacute;n y su nueva autenticaci&oacute;n.
     * <p/>
     * El valor de activaci&oacute;n del nuevo {@link Identificacion} ser&aacute; el mismo que el del {@link Identificacion} anterior.
     *
     * @param usuario             cuyo {@link Identificacion} se pretende regenerar.
     * @param cadenaRegeneracion  cadena para realizar la regeneraci&oacute;n de la autentificacion.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return el nuevo {@link Identificacion}, desactivado; <code>null</code> en caso de que el {@link Usuario} no tenga un {@link Identificacion} activo.
     *
     * @throws ManagerException si no se puede realizar la acci&oacute;n.
     */
    Identificacion regeneraIdentificacion(final Usuario usuario, final String cadenaRegeneracion, final char[] autentificacionNueva, final EnlaceTransaccional enlaceTransaccional) throws ManagerException;

}
